package com.xrui.hbase;

import java.io.Closeable;
import java.io.Flushable;
import java.io.IOException;

/**
 * Interface for performing puts on a HBase table.
 *
 * Putter provides methods for putting values into cells given an entity id,
 * column family, column qualifier, and optional timestamp, along with the value to put.
 * If a timestamp is not specified, the current system time should be used for the put.
 *
 * <pre>
 *   final Putter putter = myHBaseTable.openTableWriter();
 *   putter.put(entityId, columnFamily, columnQualifier, timestamp, value);
 *   putter.put(entityId, columnFamily, columnQualifier, value);
 * </pre>
 *
 * <p> This interface is not used alone but is bundled within {@link TableWriter}. </p>
 *
 * Unless otherwise specified, putters are not thread-safe and must be synchronized externally.
 */
public interface Putter extends Closeable, Flushable {
    /**
     * Puts data into a HBase table.
     *
     * @param entityId  The entity (row) to put data into.
     * @param family    A column family.
     * @param qualifier A column qualifier.
     * @param value     The data to write.
     * @param <T>       The type of the value being written.
     * @throws IOException If there is an IO error.
     */
    <T> void put(EntityId entityId, String family, String qualifier, T value)
        throws IOException;

    /**
     * Puts data into a HBase table.
     *
     * @param entityId  The entity (row) to put data into.
     * @param family    A column family.
     * @param qualifier A column qualifier.
     * @param timestamp Timestamp, in millisecond since the Epoch.
     * @param value     The data to write.
     * @param <T>       The type of the value being written.
     * @throws IOException If there is an IO error.
     */
    <T> void put(EntityId entityId, String family, String qualifier, long timestamp, T value)
        throws IOException;
}
